Customizing the Payment Gateway Provider
Note: To see a webinar on this topic, go to http://www.ektron.com/Resources/Webinars/Creating-Your-Own-Payment-Gateway-Provider/.
A Payment Gateway Provider is a pluggable component that is integrated into Ektron’s Ektron CMS400.NET eCommerce module. A Payment provider handles eCommerce customer payments by utilizing third party payment gateways. Ektron CMS400.NET’s eCommerce module accepts payments such as credit cards. Then, it passes that information to a third party service. The third party service processes the payment, and returns a transaction ID that’s stored with the customer's order.
Note: Your company needs to set up an account with a third party payment service before utilizing the payment provider. This includes payment providers such as Authorize.NET and PayFlow, which are included with Ektron CMS400.NET’s eCommerce Module.
Ektron CMS400.NET comes with several payment providers, including Authorize.NET and PayFlow. You can customize these providers or create your own using the extendable Payment Gateway Provider architecture.
Each type of payment gateway provider accepts configuration parameters. For example, Authorize.NET requires a username and password while PayFlow requires a username, password, vendor, and partner.
In addition, some payment gateways may support recurring payments, while others may not. Recurring payments provide the ability to create a payment that recurs at a given interval for a specified period of time. For example, you could create a payment for $9.99 that occurs on the first of every month for the next 12 months. This is something to consider if your site relies on a subscription service. Contact your provider to find out if they support recurring payments.
The following table shows the flow of payment information for a customer purchasing a product from your site through you receiving the money in your account.
|
Step |
Description |
|
1. |
A customer purchases a product from your site and submits his payment information. |
|
2. |
Ektron Ektron CMS400.NET’s passes the information to your payment gateway. |
|
3. |
Your payment gateway provider passes the information to your bank’s processor. |
|
4. |
The bank’s processor submits the information to a credit card interchange for processing, clearing and settlement. |
|
5. |
The interchange notifies the customer’s credit card company of the transactions details. |
|
6. |
The credit card company accepts or declines the transaction based on the customers account information. |
|
7. |
If the transaction is approved, the funds are transferred to the interchange. |
|
8. |
The credit card interchange sends information about whether the transaction is approved to your bank’s processor. |
|
9. |
This information is passed to your payment gateway provider. |
|
10. |
The provider notifies your site of the information. The results of the transaction are displayed on the page the customer is viewing. |
|
11. |
The credit card interchange sends funds to your merchant account. |
This section explains how to extend Ektron’s Payment Gateway Provider Architecture to build your own customized Payment Gateway Provider.
See Also: Payment Options
Payment Gateway Provider Object Model
Below is the Object Model for Ektron’s Payment Gateway Provider.
The PaymentGatewayProvider is the abstract base class you must extend to implement your own payment gateway. Details and descriptions of the PaymentGatewayProvider API can be found in the Ektron CMS400.NETAPI Reference Manual’s Providers API > PaymentGatewayProvider section.
Creating a Custom Payment Gateway Provider
In addition to the out-of-the-box payment gateways providers shipped with Ektron CMS400.NET, you can create your own custom payment providers that connect with any payment gateway you choose. Below are the basic code steps you need to complete when creating a custom gateway provider. Additional code examples used by Ektron to create the PayFlow and Authourize.NET providers are located in: C:\Program Files\Ektron\CMS400SDK\Commerce\Providers\Commerce.Providers\PaymentGateways
Note: The complete C# code sample used in this example is available at the end of this section. See CustomGatewayProvider Code Example
1. Create a class library project in Visual Studio.
2. Add references to these DLLs:
- Ektron.Cms.Commerce
- Ektron.Cms.Common
- Ektron.Cms.ObjectFactory
- Ektron.Cms.Instrumentation
- System.Configuration
3. Add these using statements to the code behind:
using System;using System.Collection;
using System.Collection.Specialized;
using Ektron.Cms;
using Ektron.Cms.Common;
using Ektron.Cms.Commerce;
4. Change the namespace to:
namespace Ektron.Cms.Extensibility.Commerce.Samples
{
5. Rename your class and inherit as below:
public class CustomPaymentProvider : Ektron.Cms.Commerce.PaymentGatewayProvider
{
6. Add the following constructor.
#region constructor, member variables
public CustomPaymentProvider() { }
#endregion
7. Add the methods required by the PaymentGatewayProvider base class. The Initialize method reads configuration information, the others are related to the payments and will be completed later in the example.
#region PaymentProvider Implementation
public override void Initialize(string name, System.Collections.Specialized.NameValueCollection config)
{
if (config == null)
throw new ArgumentNullException("config");
// Assign the provider a default name if it doesn't have one
if (String.IsNullOrEmpty(name))
name = "CustomPaymentProvider";
if (string.IsNullOrEmpty(config["description"]))
{
config.Remove("description");
config.Add("description", "CustomPaymentProvider");
}
// Call the base class's Initialize method
base.Initialize(name, config);
// Throw an exception if unrecognized attributes remain
if (config.Count > 0)
{
foreach (string key in config.AllKeys)
{
EkException.WriteToEventLog("Unrecognized Payment Gateway Provider attribute: " + key, System.Diagnostics.EventLogEntryType.Warning);
}
}
}
public override string Authorize()
{
}
public override string AuthorizeAndCapture()
{
}
public override string CapturePreauthorization(string transactionId)
{
}
public override string VoidPreAuthorization(string transactionId)
{
}
#endregion
8. Implement the Authorize method that you added in the previous step. This method is called to authorize a given amount of money when an order is submitted.
public override string Authorize()
{
if (PaymentMethod.GetType() != typeof(CreditCardPayment))
throw new Ektron.Cms.Commerce.Exceptions.AuthorizationException("Invalid Payment Type");
CreditCardPayment creditCard = (CreditCardPayment)this.PaymentMethod;
if (creditCard.ExpirationDate.IsExpired())
throw new Ektron.Cms.Commerce.Exceptions.Payment.CreditCard.CardExpiredException("Card Is Expired");
IsSubmissionSuccess = true;
Authorization.AuthorizedOn = DateTime.Now;
Authorization.TransactionId = new Guid().ToString();
return Authorization.TransactionId;
}
Note: In this example, the card number and card holder name are not checked. In a real world scenario, there would be additional validation (for example, via checksum) and the authorization may be obtained via a Web service or HTTP post.
Note: If the authorization fails, you can choose to either throw an exception or manually set the failure. For example:
SubmissionError = "Not enough Funds";IsSubmissionSuccess =
false;
9. Implement the AuthorizeAndCapture, CapturePreauthorization and VoidPreAuthorization methods you added earlier.
- AuthorizeAndCapture requires that Authorization.CapturedOn be set, as the capture occurs at the same time as the Authorization.
- For CapturePreauthorization and VoidPreAuthorization, set the appropriate dates for these actions, so they are recorded in the system properly.
public override string AuthorizeAndCapture()
{
IsSubmissionSuccess = true;
Authorization.AuthorizedOn = DateTime.Now;
Authorization.CapturedOn = DateTime.Now;
Authorization.TransactionId = new Guid().ToString();
return Authorization.TransactionId;
}
public override string CapturePreauthorization(string transactionId)
{
IsSubmissionSuccess = true;
Authorization.CapturedOn = DateTime.Now;
return Authorization.TransactionId;
}
public override string VoidPreAuthorization(string transactionId)
{
IsSubmissionSuccess = true;
Authorization.VoidedOn = DateTime.Now;
return Authorization.TransactionId;
}
10. Save and build the project.
11. Copy your project’s DLL file to your Ektron Web site’s bin directory.
12. Register the provider in your site’s Web.config file. The Web.config file provides the facility to manage payment gateway providers within Ektron CMS400.NET.
To do this, locate the EktronPaymentGateway section and change the defaultProvider parameter to the name of your custom provider. Note that changing this from “Automatic” to the name of your provider overrides the settings in Workarea > Settings > Commerce > Configuration > Payment Gateways. Ektron CMS400.NET will now use the new provider.
Note: If you start your search from the top of the file, it is the second instance.
<EktronPaymentGateway defaultProvider="CustomPaymentProvider">
13. Add your custom payment provider between the EktronPaymentGateway’s <providers> tags. Note that the name defined here must match the defaultProvider from the previous step.
<providers>
<add name="CustomPaymentProvider" type="Ektron.Cms.Extensibility.Commerce.Samples.CustomPaymentProvider, CustomPaymentProvider" />
</providers>
14. Save the Web.config file.
Next, add the payment gateway to the Workarea with the following steps.
15. Go to Workarea > Commerce > Configuration > Payment Options.
16. Select New > Payment Gateway.
17. In the Name dropdown, select customerPaymentProvider.
18. Check both Cards and Checks checkboxes.
19. Save these changes.
Your custom payment provider is now the default provider. Whenever a payment provider needs to be contacted, the information routes through the new custom provider.
Making Your Custom Provider Appear as an Option in the Workarea
In the example above, you changed the web.config file’s EktronPaymentGateway defaultProvider parameter to the name of your custom payment provider. This overrides the payment provider settings in the Workarea. If you want to manage all payment providers from the Workarea > Settings > Commerce > Configuration > Payment Gateways screen, follow these steps:
1. In the Web.config file, locate the EktronPaymentGateway section and make sure the defaultProvider parameter is set to Automatic.
<EktronPaymentGateway defaultProvider="Automatic">
2. Save the Web.config file.
3. Navigate to the Workarea > Settings > Commerce > Configuration > Payment Gateways screen.
4. Choose New > Payment Gateway.
5. Use the following table to complete the screen.
|
Field |
Description |
|
Name |
From the drop down list, select the name of the your new custom gateway. |
|
Default |
Check this box if you want this to be the default payment gateway. The default payment gateway is the gateway all payment information is routed through. |
|
User ID |
Enter the User ID for this payment gateway. This ID will identify your account with this gateway provider. |
|
Password |
Enter the password for your account with this gateway provider. |
|
Expand Custom Values |
If this gateway provider expects additional parameters when contacting it, enter those values into the Custom 1 and Custom 2 fields. |
6. Click Save (
).
The custom gateway provider has been added and can now be managed from the Workarea.
CustomGatewayProvider Code Example
Warning! Copying and pasting the code below and using it without modification to create a DLL will not result in a working custom payment provider. This code is provided as an outline of what is needed to create an actual custom payment provider.
Below is the full C# code example used in this section. See Also: Creating a Custom Payment Gateway Provider.
using System;
using System.Collections;
using System.Collections.Specialized;
using System.Configuration.Provider;
using Ektron.Cms;
using Ektron.Cms.Common;
using Ektron.Cms.Commerce;
namespace Ektron.Cms.Extensibility.Commerce.Samples
{
public class CustomPaymentProvider : Ektron.Cms.Commerce.PaymentGatewayProvider
{
public CustomPaymentProvider() { }
public override void Initialize(string name, System.Collections.Specialized.NameValueCollection config)
{
if (config == null throw new ArgumentNullException(;
// Assign the provider a default name if it doesn't have one
if (String.IsNullOrEmpty(name))
name = CustomPaymentProvider"
if string.IsNullOrEmpty(config(["description"]))
{
config.Remove("description");
config.Add("description", "CustomPaymentProvider";
}
// Call the base class's Initialize method
base.Initialize(name, config);
// Throw an exception if unrecognized attributes remain
if (config.Count > 0)
{
foreach (string key in config.AllKeys)
{
EkException.WriteToEventLog("Unrecognized Payment Gateway Provider attribute: " + key, System.Diagnostics.EventLogEntryType.Warning);
}
}
}
public override string Authorize()
{
if (PaymentMethod.GetType() != typeof(CreditCardPayment))
throw new Ektron.Cms.Commerce.Exceptions.AuthorizationException("Invalid Payment Type");
CreditCardPayment creditCard = (CreditCardPayment) this.PaymentMethod;
if (creditCard.ExpirationDate.IsExpired())
throw new Ektron.Cms.Commerce.Exceptions.Payment.CreditCard.CardExpiredException( "Card Is Expired";
IsSubmissionSuccess = true;
Authorization.AuthorizedOn = DateTime.Now;
Authorization.TransactionId = new Guid().ToString();
return Authorization.TransactionId;
}
public override string AuthorizeAndCapture()
{
IsSubmissionSuccess = true;
Authorization.AuthorizedOn = DateTime.Now;
Authorization.CapturedOn = DateTime.Now;
Authorization.TransactionId = new Guid().ToString();
return Authorization.TransactionId;
}
public override
string CapturePreauthorization(string transactionId)
{
IsSubmissionSuccess = true;
Authorization.CapturedOn = DateTime.Now;
return Authorization.TransactionId;
}
public override string VoidPreAuthorization(string transactionId)
{
IsSubmissionSuccess = true;
Authorization.VoidedOn = DateTime.Now;
return Authorization.TransactionId;
}
}
}
